<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Attaching Handlers to Queues
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot021.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc41">5.6</A>&nbsp;&nbsp;Attaching Handlers to Queues</H2><UL>
<LI><A HREF="embroot022.html#toc21">Tcl handlers</A>
<LI><A HREF="embroot022.html#toc22">ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> handlers</A>
</UL>

<A NAME="embtclhandlers"></A>
In order to handle ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> I/O on queues more conveniently,
it is possible to associate a handler with every queue, either on the Tcl
or ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side.
These handlers can be invoked automatically whenever the other side initiates
an I/O operation.<BR>
<BR>
<A NAME="toc21"></A>
<H3 CLASS="subsection"><A NAME="htoc42">5.6.1</A>&nbsp;&nbsp;Tcl handlers</H3>


<H4 CLASS="subsubsection">To-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queues</H4>
For this purpose, the to-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queue must be created with the <I>command</I> argument set. The following example creates a queue that
can be written from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, and whose contents, if flushed,
is automatically displayed in a text widget:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
Tcl:      pack [text .tout]
          ec_queue_create my_out_queue toec {ec_stream_to_window "" .tout} {}
</PRE></BLOCKQUOTE>
Assume that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is then resumed, writes to the queue and
flushes it. This will briefly pass control back to Tcl, the <B>ec_stream_to_window</B>-handler will be executed (with the stream number
added to its arguments), afterwards control is passed back to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Note that <B>ec_stream_to_window</B> is a predefined
handler which reads the whole queue contents and displays it in the
given text widget.<BR>
<BR>

<H4 CLASS="subsubsection">From-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queues</H4>
Similarly, a from-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queue could be created as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
Tcl:      ec_queue_connect my_in_queue fromec \
                        {ec_stream_input_popup "Type here:"} {}
</PRE></BLOCKQUOTE>
Assume that ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is then resumed and reads from my_in_queue.
This will briefly yield control back to Tcl, the
<B>ec_stream_input_popup</B>-handler will be executed,
afterwards control is passed back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
Three predefined handlers are provided:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default100"></A><B>ec_stream_to_window <I>tag text_widget stream_nr</I></B><DD CLASS="dd-description"><BR>
Inserts all the current contents of the specified queue stream
 at the end of the existing text_widget, using tag.
<DT CLASS="dt-description"><A NAME="@default101"></A><B>ec_stream_to_window_sync <I>tag text_widget stream_nr ?length?</I></B><DD CLASS="dd-description"><BR>
	This is provided for compatibility with the Tcl remote
	interface. This command is essentially an alias for <I>	ec_stream_to_window</I>, with an optional dummy argument <I>length</I>
	that is ignored.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default102"></A><B>ec_stream_output_popup <I>label_text stream_nr</I></B><DD CLASS="dd-description"><BR>
Pops up a window displaying the label_text,
 a text field displaying the contents of the specified queue stream,
 and an ok-button for closing.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default103"></A><B>ec_stream_input_popup <I>label_text stream_nr</I></B><DD CLASS="dd-description"><BR>
Pops up a window displaying the label_text, an input field
 and an ok-button. The text typed into the input field will
 be written into the specified queue stream.
</DL>
When ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is initialised with the default options, its <B>output</B> and
<B>error</B> streams are queues and have the <B>ec_stream_output_popup</B> handler
associated. Similarly, the <B>input</B> stream is a queue with the
<B>ec_stream_input_popup</B> handler attached.
These handler settings may be changed by the user's Tcl code.<BR>
<BR>
<A NAME="toc22"></A>
<H3 CLASS="subsection"><A NAME="htoc43">5.6.2</A>&nbsp;&nbsp;ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> handlers</H3>
<A NAME="secqevent"></A>
A to-ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> queue can be configured to
raise an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-event (see
<A HREF="../bips/kernel/event/event-1.html"><B>event/1</B></A><A NAME="@default104"></A>
and the User Manual chapter on event handling)
whenever the Tcl program writes something into the
previously empty queue.
To allow that, the queue must have been created with the <I>event</I>
argument of <B>ec_queue_create</B> set, 
e.g.<SUP><A NAME="text3" HREF="embroot016.html#note3">3</A></SUP>
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
Tcl:  set my_out_channel [ec_queue_create my_queue toec {} my_queue_event]
</PRE></BLOCKQUOTE>
Assuming something was written into the queue from within Tcl code, the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> event will be handled if the queue is flushed on the Tcl side
with the command <B>ec_flush</B>:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
Tcl:  puts $my_out_channel hello
      ec_flush [ec_streamname_to_streamnum myqueue]
</PRE></BLOCKQUOTE>
If myqueue was empty, then the <B>puts</B> would raise the event
<CODE>my_queue_event</CODE>. The <B>ec_flush</B> transfer control over to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, so that the event can be handled.<BR>
<BR>
<HR>
<A HREF="embroot021.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot016.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
